<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Macros</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Syntax-and-conditional-compilation.xhtml" title="Syntax and conditional compilation"/>
    <link rel="next" href="Named-quasi-literals.xhtml" title="Named quasi-literals"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Macros" epub:type="subchapter" id="Macros">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Macros</h2>
          </div>
        </div>
      </div>
      <span id="macro-reference"/>
      <p>Libraries and top–level programs can define and use new kinds of
derived expressions and definitions called <span class="emphasis"><em>syntactic abstractions</em></span>
or <span class="emphasis"><em>macros</em></span>.  A syntactic abstraction is created by binding a
keyword to a <span class="emphasis"><em>macro transformer</em></span> or, simply, <span class="emphasis"><em>transformer</em></span>.
</p>
      <p>The transformer determines how a use of the macro (called a <span class="emphasis"><em>macro
use</em></span>) is transcribed into a more primitive form.
</p>
      <p>Most macro uses have the form:
</p>
      <pre class="screen">(<em class="replaceable"><code>keyword</code></em> <em class="replaceable"><code>datum</code></em> …)
</pre>
      <p>where <em class="replaceable"><code>keyword</code></em> is an identifier that uniquely determines the kind
of form.  This identifier is called the <span class="emphasis"><em>syntactic keyword</em></span>, or
simply <span class="emphasis"><em>keyword</em></span>.  The number of <em class="replaceable"><code>datum</code></em>s and the syntax of
each depends on the syntactic abstraction.
</p>
      <p>Macro uses can also take the form of improper lists, singleton
identifiers, or <code class="literal">set!</code> forms, where the second subform of the
<code class="literal">set!</code> is the keyword:
</p>
      <pre class="screen">(<em class="replaceable"><code>keyword</code></em> <em class="replaceable"><code>datum</code></em> … . <em class="replaceable"><code>datum</code></em>)
<em class="replaceable"><code>keyword</code></em>
(set! <em class="replaceable"><code>keyword</code></em> <em class="replaceable"><code>datum</code></em>)
</pre>
      <p>The <code class="literal">define-syntax</code>, <code class="literal">let-syntax</code> and <code class="literal">letrec-syntax</code>
forms create bindings for keywords, associate them with macro
transformers, and control the scope within which they are visible.
</p>
      <p>The <code class="literal">syntax-rules</code> and <code class="literal">identifier-syntax</code> forms create
transformers via a pattern language.  Moreover, the <code class="literal">syntax-case</code>
form allows creating transformers via arbitrary Scheme code.
</p>
      <p>Keywords occupy the same name space as variables.  That is, within the
same scope, an identifier can be bound as a variable or keyword, or
neither, but not both, and local bindings of either kind may shadow
other bindings of either kind.
</p>
      <p>Macros defined using <code class="literal">syntax-rules</code> and <code class="literal">identifier-syntax</code>
are “hygienic” and “referentially transparent” and thus preserve
Scheme’s lexical scoping.
</p>
      <div class="itemizedlist" epub:type="list">
        <ul class="itemizedlist" style="list-style-type: disc; ">
          <li class="listitem" epub:type="list-item">
            <p>If a macro transformer inserts a binding for an identifier (variable or
keyword) not appearing in the macro use, the identifier is in effect
renamed throughout its scope to avoid conflicts with other identifiers.
</p>
          </li>
          <li class="listitem" epub:type="list-item">
            <p>If a macro transformer inserts a free reference to an identifier, the
reference refers to the binding that was visible where the transformer
was specified, regardless of any local bindings that may surround the
use of the macro.
</p>
          </li>
        </ul>
      </div>
      <p>Macros defined using the <code class="literal">syntax-case</code> facility are also hygienic
unless <code class="literal">datum-&gt;syntax</code> is used.
</p>
      <p>Kawa supports most of the <code class="literal">syntax-case</code> feature.
</p>
      <p>Syntax definitions are valid wherever definitions are.
They have the following form:
</p>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878989136" class="indexterm"/> <code class="function">define-syntax</code> <em class="replaceable"><code>keyword</code></em> <em class="replaceable"><code><a class="link" href="Macros.xhtml#meta-transformer-spec"><em class="replaceable"><code>transformer-spec</code></em></a></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The <em class="replaceable"><code>keyword</code></em> is a identifier, and <em class="replaceable"><code>transformer-spec</code></em>
is a function that maps syntax forms to syntax forms,
usually an instance of <code class="literal">syntax-rules</code>.
If the <code class="literal">define-syntax</code> occurs at the top level, then the top-level
syntactic environment is extended by binding the <em class="replaceable"><code>keyword</code></em>
to the specified transformer, but existing references to any top-level
binding for <em class="replaceable"><code>keyword</code></em> remain unchanged.  Otherwise, it is an
<em class="firstterm">internal syntax definition</em>, and is local to the <em class="replaceable"><code>body</code></em>
in which it is defined.
</p>
          <pre class="screen">(let ((x 1) (y 2))
   (define-syntax swap!
     (syntax-rules ()
       ((swap! a b)
        (let ((tmp a))
          (set! a b)
          (set! b tmp)))))
   (swap! x y)
   (list x y))  ⇒ (2 1)
</pre>
          <p>Macros can expand into definitions in any context that permits them.
However, it is an error for a definition to define an identifier
whose binding has to be known in order to determine the meaning
of the definition itself, or of any preceding definition that belongs
to the same group of internal definitions.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878979472" class="indexterm"/> <code class="function">define-syntax-case</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code><span class="bold"><strong>(</strong></span></code></em><em class="replaceable"><code>literals</code></em><em class="replaceable"><code><span class="bold"><strong>)</strong></span></code></em> <em class="replaceable"><code><span class="bold"><strong>(</strong></span></code></em><em class="replaceable"><code>pattern</code></em> <em class="replaceable"><code>expr</code></em><em class="replaceable"><code><span class="bold"><strong>)</strong></span></code></em> <em class="replaceable"><code>...</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>A convenience macro to make it easy to define <code class="literal">syntax-case</code>-style macros.
Defines a macro with the given <em class="replaceable"><code>name</code></em> and list of <em class="replaceable"><code>literals</code></em>.
Each <em class="replaceable"><code>pattern</code></em> has the form of a <code class="literal">syntax-rules</code>-style pattern,
and it is matched against the macro invocation syntax form.
When a match is found, the corresponding <em class="replaceable"><code>expr</code></em> is evaluated.
It must evaluate to a syntax form,
which replaces the macro invocation.
</p>
          <pre class="screen">(define-syntax-case macro-name (literals)
  (pat1 result1)
  (pat2 result2))
</pre>
          <p>is equivalent to:
</p>
          <pre class="screen">(define-syntax macro-name
  (lambda (form)
    (syntax-case form (literals)
      (pat1 result1)
      (pat2 result2))))
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878967888" class="indexterm"/> <code class="function">define-macro</code> <em class="replaceable"><code><span class="bold"><strong>(</strong></span></code></em><em class="replaceable"><code>name</code></em> <em class="replaceable"><code>lambda-list</code></em><em class="replaceable"><code><span class="bold"><strong>)</strong></span></code></em> <em class="replaceable"><code>form</code></em> <em class="replaceable"><code>...</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p><span class="emphasis"><em>This form is deprecated.</em></span>
Functionally equivalent to <code class="literal">defmacro</code>.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878961248" class="indexterm"/> <code class="function">defmacro</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>lambda-list</code></em> <em class="replaceable"><code>form</code></em> <em class="replaceable"><code>...</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p><span class="emphasis"><em>This form is deprecated.</em></span>
Instead of
</p>
          <pre class="screen">(defmacro (<em class="replaceable"><code>name</code></em> ...)
  (let ... `(... ,<em class="replaceable"><code>exp</code></em> ...)))
</pre>
          <p>you should probably do:
</p>
          <pre class="screen">(define-syntax-case <em class="replaceable"><code>name</code></em> ()
  ((_ ...) (let #`(... #,<em class="replaceable"><code>exp</code></em> ...))))
</pre>
          <p>and instead of
</p>
          <pre class="screen">(defmacro (<em class="replaceable"><code>name</code></em> ... <em class="replaceable"><code>var</code></em> ...) `(... <em class="replaceable"><code>var</code></em> ...))
</pre>
          <p>you should probably do:
</p>
          <pre class="screen">(define-syntax-case <em class="replaceable"><code>name</code></em> ()
  ((_ ... <em class="replaceable"><code>var</code></em> ...) #`(... <em class="replaceable"><code>var</code></em> ...))
</pre>
          <p>Defines an old-style macro a la Common Lisp,
and installs <code class="literal">(lambda <em class="replaceable"><code>lambda-list</code></em> <em class="replaceable"><code>form</code></em> ...)</code>
as the expansion function for <em class="replaceable"><code>name</code></em>.
When the translator sees an application of <em class="replaceable"><code>name</code></em>,
the expansion function is called with the rest of the application
as the actual arguments.  The resulting object must be a Scheme
source form that is futher processed (it may be repeatedly macro-expanded).
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878947024" class="indexterm"/> <code class="function">gentemp</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns a new (interned) symbol each time it is called.
The symbol names are implementation-dependent.
(This is not directly macro-related, but is often used in conjunction
with <code class="literal">defmacro</code> to get a fresh unique identifier.)
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878943440" class="indexterm"/> <code class="function">expand</code> <em class="replaceable"><code>form</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>The result of evaluating <em class="replaceable"><code>form</code></em> is treated as a Scheme expression,
syntax-expanded to internal form, and then converted back to (roughly)
the equivalent expanded Scheme form.
</p>
          <p>This can be useful for debugging macros.
</p>
          <p>To access this function, you must first <code class="literal">(require 'syntax-utils)</code>.
</p>
          <pre class="screen">(require 'syntax-utils)
(expand '(cond ((&gt; x y) 0) (else 1))) ⇒ (if (&gt; x y) 0 1)
</pre>
        </blockquote>
      </div>
      <section class="sect2" title="Pattern language" epub:type="division" id="idm139667878937936">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Pattern language</h3>
            </div>
          </div>
        </div>
        <p>A <em class="replaceable"><code>transformer-spec</code></em> is an expression that evaluates to a
transformer procedure, which takes an input form and returns a
resulting form.  You can do general macro-time compilation with such a
procedure, commonly using <code class="literal">syntax-case</code> (which is documented
in the R6RS library specification).
However, when possible it is better to use the simpler
pattern language of <code class="literal">syntax-rules</code>:
</p>
        <div class="literallayout">
          <p><a id="idm139667878934880" class="indexterm"/><span id="meta-transformer-spec"/><em class="replaceable"><code>transformer-spec</code></em> <code class="literal">::=</code><br/>
  <code class="literal"><span class="bold"><strong>(syntax-rules (</strong></span></code> <a class="link" href="Macros.xhtml#meta-tr-literal"><em class="replaceable"><code>tr-literal</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-rule"><em class="replaceable"><code>syntax-rule</code></em></a><sup>*</sup><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(syntax-rules</strong></span></code> <a class="link" href="Macros.xhtml#meta-ellipsis"><em class="replaceable"><code>ellipsis</code></em></a> <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Macros.xhtml#meta-tr-literal"><em class="replaceable"><code>tr-literal</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-rule"><em class="replaceable"><code>syntax-rule</code></em></a><sup>*</sup><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <a class="link" href="Primitive-expression-syntax.xhtml#meta-expression"><em class="replaceable"><code>expression</code></em></a><br/>
<a id="idm139667878921616" class="indexterm"/><span id="meta-syntax-rule"/><em class="replaceable"><code>syntax-rule</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>(</strong></span></code><a class="link" href="Macros.xhtml#meta-list-pattern"><em class="replaceable"><code>list-pattern</code></em></a> <a class="link" href="Macros.xhtml#meta-syntax-template"><em class="replaceable"><code>syntax-template</code></em></a><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
<a id="idm139667878916688" class="indexterm"/><span id="meta-tr-literal"/><em class="replaceable"><code>tr-literal</code></em> <code class="literal">::=</code> <a class="link" href="Lexical-syntax.xhtml#meta-identifier"><em class="replaceable"><code>identifier</code></em></a><br/>
<a id="idm139667878913888" class="indexterm"/><span id="meta-ellipsis"/><em class="replaceable"><code>ellipsis</code></em> <code class="literal">::=</code> <a class="link" href="Lexical-syntax.xhtml#meta-identifier"><em class="replaceable"><code>identifier</code></em></a><br/>
</p>
        </div>
        <p>An instance of <code class="literal">syntax-rules</code> produces a new
macro transformer by specifying a sequence of hygienic
rewrite rules. A use of a macro whose keyword is associated
with a transformer specified by <code class="literal">syntax-rules</code> is matched
against the patterns contained in the <em class="replaceable"><code>syntax-rule</code></em>s
beginning with the leftmost syntax rule . When a match is
found, the macro use is transcribed hygienically according
to the template.
The optional <em class="replaceable"><code>ellipsis</code></em> species a symbol used to indicate
repetition; it defaults to <code class="literal">...</code> (3 periods).
</p>
        <div class="literallayout">
          <p><a id="idm139667878907856" class="indexterm"/><span id="meta-syntax-pattern"/><em class="replaceable"><code>syntax-pattern</code></em> <code class="literal">::=</code><br/>
  <a class="link" href="Lexical-syntax.xhtml#meta-identifier"><em class="replaceable"><code>identifier</code></em></a> | <a class="link" href="Primitive-expression-syntax.xhtml#meta-constant"><em class="replaceable"><code>constant</code></em></a> | <a class="link" href="Macros.xhtml#meta-list-pattern"><em class="replaceable"><code>list-pattern</code></em></a> | <a class="link" href="Macros.xhtml#meta-vector-pattern"><em class="replaceable"><code>vector-pattern</code></em></a><br/>
<a id="idm139667878902608" class="indexterm"/><span id="meta-list-pattern"/><em class="replaceable"><code>list-pattern</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>.</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a> <code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a> <a class="link" href="Macros.xhtml#meta-ellipsis"><em class="replaceable"><code>ellipsis</code></em></a> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a> <a class="link" href="Macros.xhtml#meta-ellipsis"><em class="replaceable"><code>ellipsis</code></em></a> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>.</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
<a id="idm139667878880672" class="indexterm"/><span id="meta-vector-pattern"/><em class="replaceable"><code>vector-pattern</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>#(</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>#(</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a> <a class="link" href="Macros.xhtml#meta-ellipsis"><em class="replaceable"><code>ellipsis</code></em></a> <a class="link" href="Macros.xhtml#meta-syntax-pattern"><em class="replaceable"><code>syntax-pattern</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
</p>
        </div>
        <p>An identifier appearing within a pattern can be an underscore
(<code class="literal">_</code>), a literal identifier listed in the list of <em class="replaceable"><code>tr-literal</code></em>s,
or the <em class="replaceable"><code>ellipsis</code></em>. All other identifiers appearing within a
pattern are pattern variables.
</p>
        <p>The outer <em class="replaceable"><code>syntax-list</code></em> of the pattern in a <em class="replaceable"><code>syntax-rule</code></em>
must start with an identifier. It is not involved in the matching and
is considered neither a pattern variable nor a literal identifier.
</p>
        <p>Pattern variables match arbitrary input elements and are
used to refer to elements of the input in the template.
It is an error for the same pattern variable to appear more
than once in a <em class="replaceable"><code>syntax-pattern</code></em>.
</p>
        <p>Underscores also match arbitrary input elements but are
not pattern variables and so cannot be used to refer to
those elements. If an underscore appears in the literals
list, then that takes precedence and underscores in the
pattern match as literals. Multiple underscores can
appear in a <em class="replaceable"><code>syntax-pattern</code></em>.
</p>
        <p>Identifiers that appear in <code class="literal">(<em class="replaceable"><code>tr-literal</code></em><sup>*</sup>)</code> are interpreted
as literal identifiers to be matched against corresponding
elements of the input. An element in the input matches a
literal identifier if and only if it is an identifier and either
both its occurrence in the macro expression and its occurrence
in the macro definition have the same lexical binding,
or the two identifiers are the same and both have no lexical
binding.
</p>
        <p>A subpattern followed by ellipsis can match zero or
more elements of the input, unless ellipsis appears in the
literals, in which case it is matched as a literal.
</p>
        <p>More formally, an input expression <em class="replaceable"><code>E</code></em> matches a pattern <em class="replaceable"><code>P</code></em>
if and only if:
</p>
        <div class="itemizedlist" epub:type="list">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is an underscore (<code class="literal"><span class="bold"><strong>_</strong></span></code>); or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is a non-literal identifier; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is a literal identifier and <em class="replaceable"><code>E</code></em> is an identifier with the
same binding; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is a list <code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>P<sub>1</sub></code></em> ... <em class="replaceable"><code>P<sub>n</sub></code></em><code class="literal"><span class="bold"><strong>)</strong></span></code> and
<em class="replaceable"><code>E</code></em> is a list of <em class="replaceable"><code>n</code></em> elements
that match <em class="replaceable"><code>P<sub>1</sub></code></em> through <em class="replaceable"><code>P<sub>n</sub></code></em>, respectively; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is an improper list
<code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>P<sub>1</sub></code></em> ... <em class="replaceable"><code>P<sub>n</sub></code></em> <code class="literal"><span class="bold"><strong>.</strong></span></code> <em class="replaceable"><code>P<sub>n+1</sub></code></em><code class="literal"><span class="bold"><strong>)</strong></span></code> and
<em class="replaceable"><code>E</code></em> is a list or improper list of <em class="replaceable"><code>n</code></em> or more elements that
match <em class="replaceable"><code>P<sub>1</sub></code></em> through <em class="replaceable"><code>P<sub>n</sub></code></em>, respectively,
and whose <em class="replaceable"><code>n</code></em>th tail matches <em class="replaceable"><code>P<sub>n+1</sub></code></em>; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is of the form
<code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>P<sub>1</sub></code></em> ... <em class="replaceable"><code>P<sub>k</sub></code></em> <em class="replaceable"><code>P<sub>e</sub></code></em> <em class="replaceable"><code>ellipsis</code></em> <em class="replaceable"><code>P<sub>k+1</sub></code></em> ... <em class="replaceable"><code>P<sub>k+l</sub></code></em><code class="literal"><span class="bold"><strong>)</strong></span></code> where <em class="replaceable"><code>E</code></em> is a proper list of <em class="replaceable"><code>n</code></em> elements,
 the first <em class="replaceable"><code>k</code></em> of which match <em class="replaceable"><code>P<sub>1</sub></code></em> through <em class="replaceable"><code>P<sub>k</sub></code></em>,
respectively, whose
next <em class="replaceable"><code>n-k-l</code></em> elements each match <em class="replaceable"><code>P<sub>e</sub></code></em>, and whose remaining
<em class="replaceable"><code>l</code></em> elements match <em class="replaceable"><code>P<sub>k+1</sub></code></em> through <em class="replaceable"><code>P<sub>k+l</sub></code></em>; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is of the form
<code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>P<sub>1</sub></code></em> ... <em class="replaceable"><code>P<sub>k</sub></code></em> <em class="replaceable"><code>P<sub>e</sub></code></em> <em class="replaceable"><code>ellipsis</code></em> <em class="replaceable"><code>P<sub>k+1</sub></code></em> ... <em class="replaceable"><code>P<sub>k+l</sub></code></em> <code class="literal"><span class="bold"><strong>.</strong></span></code> <em class="replaceable"><code>P<sub>x</sub></code></em><code class="literal"><span class="bold"><strong>)</strong></span></code>
where <em class="replaceable"><code>E</code></em> is a list or improper list of <em class="replaceable"><code>n</code></em> elements,
the first <em class="replaceable"><code>k</code></em> of which match <em class="replaceable"><code>P<sub>1</sub></code></em> through <em class="replaceable"><code>P<sub>k</sub></code></em>,
whose next <em class="replaceable"><code>n-k-l</code></em> elements each match <em class="replaceable"><code>P<sub>e</sub></code></em>, and whose
remaining <em class="replaceable"><code>l</code></em> elements match <em class="replaceable"><code>P<sub>k+1</sub></code></em> through <em class="replaceable"><code>P<sub>k+l</sub></code></em>,
and whose <em class="replaceable"><code>n</code></em>th and final <code class="literal">cdr</code> matches <em class="replaceable"><code>P<sub>x</sub></code></em>; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is a vector of the form
<code class="literal"><span class="bold"><strong>#(</strong></span></code><em class="replaceable"><code>P<sub>1</sub></code></em> ... <em class="replaceable"><code>P<sub>n</sub></code></em><code class="literal"><span class="bold"><strong>)</strong></span></code> and <em class="replaceable"><code>E</code></em> is a
vector of <em class="replaceable"><code>n</code></em> elements that match <em class="replaceable"><code>P<sub>1</sub></code></em> through <em class="replaceable"><code>P<sub>n</sub></code></em>; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is of the form
<code class="literal"><span class="bold"><strong>#(</strong></span></code><em class="replaceable"><code>P<sub>1</sub></code></em> ... <em class="replaceable"><code>P<sub>k</sub></code></em> <em class="replaceable"><code>P<sub>e</sub></code></em> <em class="replaceable"><code>ellipsis</code></em> <em class="replaceable"><code>P<sub>k+1</sub></code></em> ... <em class="replaceable"><code>P<sub>k+l</sub></code></em><code class="literal"><span class="bold"><strong>)</strong></span></code>
where <em class="replaceable"><code>E</code></em> is a vector of <em class="replaceable"><code>n</code></em> elements the first
<em class="replaceable"><code>k</code></em> of which match <em class="replaceable"><code>P<sub>1</sub></code></em> through <em class="replaceable"><code>P<sub>k</sub></code></em>,
whose next <em class="replaceable"><code>n-k-l</code></em> elements each match <em class="replaceable"><code>P<sub>e</sub></code></em>,
and whose remaining <em class="replaceable"><code>l</code></em> elements match <em class="replaceable"><code>P<sub>k+1</sub></code></em>
through <em class="replaceable"><code>P<sub>k+l</sub></code></em>; or
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p><em class="replaceable"><code>P</code></em> is a constant and E is equal to <em class="replaceable"><code>P</code></em> in the sense of the
<code class="literal">equal?</code> procedure.
</p>
            </li>
          </ul>
        </div>
        <p>It is an error to use a macro keyword, within the scope of
its binding, in an expression that does not match any of
the patterns.
</p>
        <div class="literallayout">
          <p><a id="idm139667878800240" class="indexterm"/><span id="meta-syntax-template"/><em class="replaceable"><code>syntax-template</code></em> <code class="literal">::=</code> <a class="link" href="Lexical-syntax.xhtml#meta-identifier"><em class="replaceable"><code>identifier</code></em></a> | <a class="link" href="Primitive-expression-syntax.xhtml#meta-constant"><em class="replaceable"><code>constant</code></em></a><br/>
   | <code class="literal"><span class="bold"><strong>(</strong></span></code><a class="link" href="Macros.xhtml#meta-template-element"><em class="replaceable"><code>template-element</code></em></a><sup>*</sup><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
   | <code class="literal"><span class="bold"><strong>(</strong></span></code><a class="link" href="Macros.xhtml#meta-template-element"><em class="replaceable"><code>template-element</code></em></a> <a class="link" href="Macros.xhtml#meta-template-element"><em class="replaceable"><code>template-element</code></em></a><sup>*</sup> <code class="literal"><span class="bold"><strong>.</strong></span></code> <a class="link" href="Macros.xhtml#meta-syntax-template"><em class="replaceable"><code>syntax-template</code></em></a> <code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
   | <code class="literal"><span class="bold"><strong>(</strong></span></code> <a class="link" href="Macros.xhtml#meta-ellipsis"><em class="replaceable"><code>ellipsis</code></em></a> <a class="link" href="Macros.xhtml#meta-syntax-template"><em class="replaceable"><code>syntax-template</code></em></a><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
<a id="idm139667878786144" class="indexterm"/><span id="meta-template-element"/><em class="replaceable"><code>template-element</code></em> <code class="literal">::=</code> <a class="link" href="Macros.xhtml#meta-syntax-template"><em class="replaceable"><code>syntax-template</code></em></a> [<a class="link" href="Macros.xhtml#meta-ellipsis"><em class="replaceable"><code>ellipsis</code></em></a>]<br/>
</p>
        </div>
        <p>When a macro use is transcribed according to the template
of the matching <em class="replaceable"><code>syntax-rule</code></em>, pattern variables that occur
in the template are replaced by the elements they match in
the input. Pattern variables that occur in subpatterns followed
by one or more instances of the identifier <em class="replaceable"><code>ellipsis</code></em> are
allowed only in subtemplates that are followed by as many
instances of <em class="replaceable"><code>ellipsis</code></em> . They are replaced in the output by
all of the elements they match in the input, distributed as
indicated. It is an error if the output cannot be built up
as specified.
</p>
        <p>Identifiers that appear in the template but are not pattern
variables or the identifier <em class="replaceable"><code>ellipsis</code></em> are inserted into the output
as literal identifiers. If a literal identifier is inserted as a
free identifier then it refers to the binding of that identifier
within whose scope the instance of <code class="literal">syntax-rules</code> appears.
If a literal identifier is inserted as a bound identifier then
it is in effect renamed to prevent inadvertent captures of
free identifiers.
</p>
        <p>A template of the
form <code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>ellipsis</code></em> <em class="replaceable"><code>template</code></em><code class="literal"><span class="bold"><strong>)</strong></span></code> is
identical to <em class="replaceable"><code>template</code></em>, except that <em class="replaceable"><code>ellipses</code></em>
within the template have no special meaning.
That is, any <em class="replaceable"><code>ellipses</code></em> contained within
<em class="replaceable"><code>template</code></em> are treated as ordinary identifiers. In particular,
the template <code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>ellipsis</code></em>  <em class="replaceable"><code>ellipsis</code></em><code class="literal"><span class="bold"><strong>)</strong></span></code>
produces a single <em class="replaceable"><code>ellipsis</code></em>. This allows syntactic
abstractions to expand into code containing ellipses.
</p>
        <pre class="screen">(define-syntax be-like-begin
  (syntax-rules ()
    ((be-like-begin name)
     (define-syntax name
       (syntax-rules ()
         ((name expr (... ...))
          (begin expr (... ...))))))))

(be-like-begin sequence)
(sequence 1 2 3 4) ⇒ 4
</pre>
      </section>
      <section class="sect2" title="Identifier predicates" epub:type="division" id="idm139667878770304">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Identifier predicates</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878769232" class="indexterm"/> <code class="function">identifier?</code> <em class="replaceable"><code><em class="replaceable"><code>obj</code></em></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return <code class="literal">#t</code> if <em class="replaceable"><code>obj</code></em> is an identifier, i.e., a syntax object
representing an identifier, and <code class="literal">#f</code> otherwise.
</p>
            <p>The <code class="literal">identifier?</code> procedure is often used within a fender to verify
that certain subforms of an input form are identifiers, as in the
definition of <code class="literal">rec</code>, which creates self–contained recursive
objects, below.
</p>
            <pre class="screen">(define-syntax rec
  (lambda (x)
    (syntax-case x ()
      ((_ x e)
       (identifier? #'x)
       #'(letrec ((x e)) x)))))

(map (rec fact
       (lambda (n)
         (if (= n 0)                 
             1
             (* n (fact (- n 1))))))
     '(1 2 3 4 5))    ⇒ (1 2 6 24 120)
 
(rec 5 (lambda (x) x))  ⇒ exception
</pre>
          </blockquote>
        </div>
        <p>The procedures <code class="literal">bound-identifier=?</code> and <code class="literal">free-identifier=?</code>
each take two identifier arguments and return <code class="literal">#t</code> if their arguments
are equivalent and <code class="literal">#f</code> otherwise.  These predicates are used to
compare identifiers according to their <span class="emphasis"><em>intended use</em></span> as free
references or bound identifiers in a given context.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878759200" class="indexterm"/> <code class="function">bound-identifier=?</code> <em class="replaceable"><code><em class="replaceable"><code>id</code></em></code></em><em class="replaceable"><code><sub>1</sub></code></em> <em class="replaceable"><code><em class="replaceable"><code>id</code></em></code></em><em class="replaceable"><code><sub>2</sub></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p><em class="replaceable"><code>id</code></em><sub>1</sub> and <em class="replaceable"><code>id</code></em><sub>2</sub> must be identifiers.
</p>
            <p>The procedure <code class="literal">bound-identifier=?</code> returns <code class="literal">#t</code> if a binding for
one would capture a reference to the other in the output of the
transformer, assuming that the reference appears within the scope of the
binding, and <code class="literal">#f</code> otherwise.
</p>
            <p>In general, two identifiers are <code class="literal">bound-identifier=?</code> only if both
are present in the original program or both are introduced by the same
transformer application (perhaps implicitly, see <code class="literal">datum-&gt;syntax</code>).
</p>
            <p>The <code class="literal">bound-identifier=?</code> procedure can be used for detecting
duplicate identifiers in a binding construct or for other preprocessing
of a binding construct that requires detecting instances of the bound
identifiers.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878748960" class="indexterm"/> <code class="function">free-identifier=?</code> <em class="replaceable"><code><em class="replaceable"><code>id</code></em></code></em><em class="replaceable"><code><sub>1</sub></code></em> <em class="replaceable"><code><em class="replaceable"><code>id</code></em></code></em><em class="replaceable"><code><sub>2</sub></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p><em class="replaceable"><code>id</code></em><sub>1</sub> and <em class="replaceable"><code>id</code></em><sub>2</sub> must be identifiers.
</p>
            <p>The <code class="literal">free-identifier=?</code> procedure returns <code class="literal">#t</code> if and only if
the two identifiers would resolve to the same binding if both were to
appear in the output of a transformer outside of any bindings inserted
by the transformer.  (If neither of two like–named identifiers resolves
to a binding, i.e., both are unbound, they are considered to resolve to
the same binding.)
</p>
            <p>Operationally, two identifiers are considered equivalent by
<code class="literal">free-identifier=?</code> if and only the topmost matching substitution
for each maps to the same binding or the identifiers have the same name
and no matching substitution.
</p>
            <p>The <code class="literal">syntax-case</code> and <code class="literal">syntax-rules</code> forms internally use
<code class="literal">free-identifier=?</code> to compare identifiers listed in the literals
list against input identifiers.
</p>
            <pre class="screen">(let ((fred 17))
  (define-syntax a
    (lambda (x)
      (syntax-case x ()
        ((_ id) #'(b id fred)))))
  (define-syntax b
    (lambda (x)
      (syntax-case x ()
        ((_ id1 id2)
         #`(list
             #,(free-identifier=? #'id1 #'id2)
             #,(bound-identifier=? #'id1 #'id2))))))
  (a fred))
    ⇒ (#t #f)
</pre>
            <p>The following definition of unnamed <code class="literal">let</code> uses
<code class="literal">bound-identifier=?</code> to detect duplicate identifiers.
</p>
            <pre class="screen">(define-syntax let
  (lambda (x)
    (define unique-ids?
      (lambda (ls)
        (or (null? ls)
            (and (let notmem? ((x (car ls)) (ls (cdr ls)))
                   (or (null? ls)
                       (and (not (bound-identifier=? x (car ls)))
                            (notmem? x (cdr ls)))))
                 (unique-ids? (cdr ls))))))
    (syntax-case x ()
      ((_ ((i v) ...) e1 e2 ...)
       (unique-ids? #'(i ...))
       #'((lambda (i ...) e1 e2 ...) v ...)))))
</pre>
            <p>The argument <code class="literal">#'(i ...)</code> to <code class="literal">unique-ids?</code> is guaranteed to be
a list by the rules given in the description of <code class="literal">syntax</code> above.
</p>
            <p>With this definition of <code class="literal">let</code>:
</p>
            <pre class="screen">(let ((a 3) (a 4)) (+ a a))    ⇒ <span class="emphasis"><em>syntax error</em></span>
</pre>
            <p>However,
</p>
            <pre class="screen">(let-syntax
  ((dolet (lambda (x)
            (syntax-case x ()
              ((_ b)
               #'(let ((a 3) (b 4)) (+ a b)))))))
  (dolet a))
⇒ 7
</pre>
            <p>since the identifier <code class="literal">a</code> introduced by <code class="literal">dolet</code> and the
identifier <code class="literal">a</code> extracted from the input form are not
<code class="literal">bound-identifier=?</code>.
</p>
            <p>Rather than including <code class="literal">else</code> in the literals list as before, this
version of <code class="literal">case</code> explicitly tests for <code class="literal">else</code> using
<code class="literal">free-identifier=?</code>.
</p>
            <pre class="screen">(define-syntax case
  (lambda (x)
    (syntax-case x ()
      ((_ e0 ((k ...) e1 e2 ...) ...
          (else-key else-e1 else-e2 ...))
       (and (identifier? #'else-key)
            (free-identifier=? #'else-key #'else))
       #'(let ((t e0))
           (cond
            ((memv t '(k ...)) e1 e2 ...)
            ...
            (else else-e1 else-e2 ...))))
      ((_ e0 ((ka ...) e1a e2a ...)
          ((kb ...) e1b e2b ...) ...)
       #'(let ((t e0))
           (cond
            ((memv t '(ka ...)) e1a e2a ...)
            ((memv t '(kb ...)) e1b e2b ...)
            ...))))))
</pre>
            <p>With either definition of <code class="literal">case</code>, <code class="literal">else</code> is not recognized as
an auxiliary keyword if an enclosing lexical binding for <code class="literal">else</code>
exists.  For example,
</p>
            <pre class="screen">(let ((else <code class="literal">#f</code>))
  (case 0 (else (write "oops"))))    ⇒ <span class="emphasis"><em>syntax error</em></span>
</pre>
            <p>since <code class="literal">else</code> is bound lexically and is therefore not the same
<code class="literal">else</code> that appears in the definition of <code class="literal">case</code>.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Syntax-object and datum conversions" epub:type="division" id="idm139667878720528">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Syntax-object and datum conversions</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878719440" class="indexterm"/> <code class="function">syntax-&gt;datum</code> <em class="replaceable"><code><em class="replaceable"><code>syntax-object</code></em></code></em></p>
        <p class="synopsis" kind="Deprecated procedure"><span class="kind">Deprecated procedure</span><span class="ignore">: </span><a id="idm139667878716480" class="indexterm"/> <code class="function">syntax-object-&gt;datum</code> <em class="replaceable"><code><em class="replaceable"><code>syntax-object</code></em></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Strip all syntactic information from a syntax object and returns the
corresponding Scheme datum.
</p>
            <p>Identifiers stripped in this manner are converted to their symbolic
names, which can then be compared with <code class="literal">eq?</code>.  Thus, a predicate
<code class="literal">symbolic-identifier=?</code> might be defined as follows.
</p>
            <pre class="screen">(define symbolic-identifier=?
  (lambda (x y)
    (eq? (syntax-&gt;datum x)
         (syntax-&gt;datum y))))
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878710944" class="indexterm"/> <code class="function">datum-&gt;syntax</code> <em class="replaceable"><code><em class="replaceable"><code>template-id</code></em></code></em> <em class="replaceable"><code><em class="replaceable"><code>datum</code></em></code></em> [<em class="replaceable"><code><em class="replaceable"><code>srcloc</code></em></code></em>]</p>
        <p class="synopsis" kind="Deprecated procedure"><span class="kind">Deprecated procedure</span><span class="ignore">: </span><a id="idm139667878706768" class="indexterm"/> <code class="function">datum-&gt;syntax-object</code> <em class="replaceable"><code><em class="replaceable"><code>template-id</code></em></code></em> <em class="replaceable"><code><em class="replaceable"><code>datum</code></em></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p><em class="replaceable"><code>template-id</code></em> must be a template identifier and <em class="replaceable"><code>datum</code></em> should
be a datum value.
</p>
            <p>The <code class="literal">datum-&gt;syntax</code> procedure returns a syntax-object
representation of <em class="replaceable"><code>datum</code></em> that contains the same contextual
information as <em class="replaceable"><code>template-id</code></em>, with the effect that the syntax object
behaves as if it were introduced into the code when <em class="replaceable"><code>template-id</code></em>
was introduced.
</p>
            <p>If <em class="replaceable"><code>srcloc</code></em> is specified (and neither <code class="literal">#f</code> or <code class="literal">#!null</code>),
it specifies the file position (including line number) for the result.
In that case it should be a syntax object representing
a list; otherwise it is currently ignored, though future extensions
may support other ways of specifying the position.
</p>
            <p>The <code class="literal">datum-&gt;syntax</code> procedure allows a transformer to “bend”
lexical scoping rules by creating <span class="emphasis"><em>implicit identifiers</em></span> that
behave as if they were present in the input form, thus permitting the
definition of macros that introduce visible bindings for or references
to identifiers that do not appear explicitly in the input form.  For
example, the following defines a <code class="literal">loop</code> expression that uses this
controlled form of identifier capture to bind the variable <code class="literal">break</code>
to an escape procedure within the loop body.  (The derived
<code class="literal">with-syntax</code> form is like <code class="literal">let</code> but binds pattern variables.)
</p>
            <pre class="screen">(define-syntax loop
  (lambda (x)
    (syntax-case x ()
      ((k e ...)
       (with-syntax
           ((break (datum-&gt;syntax #'k 'break)))
         #'(call-with-current-continuation
             (lambda (break)
               (let f () e ... (f)))))))))

(let ((n 3) (ls '()))
  (loop
    (if (= n 0) (break ls))
    (set! ls (cons 'a ls))
    (set! n (- n 1))))
⇒ (a a a)
</pre>
            <p>Were <code class="literal">loop</code> to be defined as:
</p>
            <pre class="screen">(define-syntax loop
  (lambda (x)
    (syntax-case x ()
      ((_ e ...)
       #'(call-with-current-continuation
           (lambda (break)
             (let f () e ... (f))))))))
</pre>
            <p>the variable <code class="literal">break</code> would not be visible in <code class="literal">e ...</code>.
</p>
            <p>The datum argument <em class="replaceable"><code>datum</code></em> may also represent an arbitrary Scheme
form, as demonstrated by the following definition of <code class="literal">include</code>.
</p>
            <pre class="screen">(define-syntax include
  (lambda (x)
    (define read-file
      (lambda (fn k)
        (let ((p (open-file-input-port fn)))
          (let f ((x (get-datum p)))
            (if (eof-object? x)
                (begin (close-port p) '())
                (cons (datum-&gt;syntax k x)
                      (f (get-datum p))))))))
    (syntax-case x ()
      ((k filename)
       (let ((fn (syntax-&gt;datum #'filename)))
         (with-syntax (((exp ...)
                        (read-file fn #'k)))
           #'(begin exp ...)))))))
</pre>
            <p><code class="literal">(include "filename")</code> expands into a <code class="literal">begin</code> expression
containing the forms found in the file named by <code class="literal">"filename"</code>.  For
example, if the file <code class="filename">flib.ss</code> contains:
</p>
            <pre class="screen">(define f (lambda (x) (g (* x x))))
</pre>
            <p>and the file <code class="filename">glib.ss</code> contains:
</p>
            <pre class="screen">(define g (lambda (x) (+ x x)))
</pre>
            <p>the expression:
</p>
            <pre class="screen">(let ()
  (include "flib.ss")
  (include "glib.ss")
  (f 5))
</pre>
            <p>evaluates to <code class="literal">50</code>.
</p>
            <p>The definition of <code class="literal">include</code> uses <code class="literal">datum-&gt;syntax</code> to convert
the objects read from the file into syntax objects in the proper lexical
context, so that identifier references and definitions within those
expressions are scoped where the <code class="literal">include</code> form appears.
</p>
            <p>Using <code class="literal">datum-&gt;syntax</code>, it is even possible to break hygiene
entirely and write macros in the style of old Lisp macros.  The
<code class="literal">lisp-transformer</code> procedure defined below creates a transformer
that converts its input into a datum, calls the programmer’s procedure
on this datum, and converts the result back into a syntax object scoped
where the original macro use appeared.
</p>
            <pre class="screen">(define lisp-transformer
  (lambda (p)
    (lambda (x)
      (syntax-case x ()
        ((kwd . rest)
         (datum-&gt;syntax #'kwd
           (p (syntax-&gt;datum x))))))))
</pre>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Signaling errors in macro transformers" epub:type="division" id="idm139667878677280">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Signaling errors in macro transformers</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878676192" class="indexterm"/> <code class="function">syntax-error</code> <em class="replaceable"><code>message</code></em> <em class="replaceable"><code>args</code></em><em class="replaceable"><code><sup>*</sup></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The <em class="replaceable"><code>message</code></em> and <em class="replaceable"><code>args</code></em> are treated similary as for
the <code class="literal">error</code> procedure.  However, the error is reported
when the <code class="literal">syntax-error</code> is expanded.
This can be used as a <code class="literal">syntax-rules</code>
template for a pattern that is an invalid use of the
macro, which can provide more descriptive error messages.
The <em class="replaceable"><code>message</code></em> should be a string literal, and the <em class="replaceable"><code>args</code></em>
arbitrary (non-evalualted) expressions providing additional information.
</p>
            <pre class="screen">(define-syntax simple-let
  (syntax-rules ()
    ((_ (head ... ((x . y) val) . tail)
       body1 body2 ...)
     (syntax-error "expected an identifier but got" (x . y)))
    ((_ ((name val) ...) body1 body2 ...)
     ((lambda (name ...) body1 body2 ...)
      val ...))))
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667878667488" class="indexterm"/> <code class="function">report-syntax-error</code> <em class="replaceable"><code>location</code></em> <em class="replaceable"><code>message</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>This is a procedure that can be called at macro-expansion time
by a syntax transformer function.
(In contrast <code class="literal">syntax-error</code> is a syntax form used in the
expansion result.)
The <em class="replaceable"><code>message</code></em> is reported as a compile-time error message.
The <em class="replaceable"><code>location</code></em> is used for the source location (file name and
line/column numbers): In general it can be a <code class="literal">SourceLocator</code> value;
most commonly it is a syntax object for a sub-list of the input form
that is erroneous.
The value returned by <code class="literal">report-syntax-error</code> is an
instance of <code class="literal">ErrorExp</code>, which supresses further compilation.
</p>
            <pre class="screen">(define-syntax if
  (lambda (x)
    (syntax-case x ()
                 ((_ test then)
                  (make-if-exp #'test #'then #!null))
                 ((_ test then else)
                  (make-if-exp #'test #'then #'else))
                 ((_ e1 e2 e3 . rest)
                  (report-syntax-error #'rest
                   "too many expressions for 'if'"))
                 ((_ . rest)
                  (report-syntax-error #'rest
                   "too few expressions for 'if'")))))
</pre>
            <p>In the above example, one could use the source form <code class="literal">x</code> for the
location, but using <code class="literal">#'rest</code> is more accurate.  Note that the following
is incorrect, because <code class="literal">e1</code> might not be a pair, in which case
we don’t have location information for it (due to a Kawa limitation):
</p>
            <pre class="screen">    (syntax-case x ()
                 ...
                 ((_ e1)
                  (report-syntax-error
                   #'e1 ;; <span class="emphasis"><em>poor location specifier</em></span>
                   "too few expressions for 'if'")))))
</pre>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Convenience forms" epub:type="division" id="idm139667878656608">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Convenience forms</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878655536" class="indexterm"/> <code class="function">with-syntax</code> ((<em class="replaceable"><code><em class="replaceable"><code>pattern</code></em></code></em> <em class="replaceable"><code><a class="link" href="Primitive-expression-syntax.xhtml#meta-expression"><em class="replaceable"><code>expression</code></em></a></code></em>) <em class="replaceable"><code>…</code></em>) <em class="replaceable"><code><a class="link" href="Bodies.xhtml#meta-body"><em class="replaceable"><code>body</code></em></a></code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The <code class="literal">with-syntax</code> form is used to bind pattern variables, just as
<code class="literal">let</code> is used to bind variables.  This allows a transformer to
construct its output in separate pieces, then put the pieces together.
</p>
            <p>Each <em class="replaceable"><code>pattern</code></em> is identical in form to a <code class="literal">syntax-case</code>
pattern.  The value of each <em class="replaceable"><code>expression</code></em> is computed and
destructured according to the corresponding <em class="replaceable"><code>pattern</code></em>, and pattern
variables within the <em class="replaceable"><code>pattern</code></em> are bound as with
<code class="literal">syntax-case</code> to the corresponding portions of the value within
<em class="replaceable"><code>body</code></em>.
</p>
            <p>The <code class="literal">with-syntax</code> form may be defined in terms of
<code class="literal">syntax-case</code> as follows.
</p>
            <pre class="screen">(define-syntax with-syntax
  (lambda (x)
    (syntax-case x ()
      ((_ ((p e0) ...) e1 e2 ...)
       (syntax (syntax-case (list e0 ...) ()
                 ((p ...) (let () e1 e2 ...))))))))
</pre>
            <p>The following definition of <code class="literal">cond</code> demonstrates the use of
<code class="literal">with-syntax</code> to support transformers that employ recursion
internally to construct their output.  It handles all <code class="literal">cond</code> clause
variations and takes care to produce one-armed <code class="literal">if</code> expressions
where appropriate.
</p>
            <pre class="screen">(define-syntax cond
  (lambda (x)
    (syntax-case x ()
      ((_ c1 c2 ...)
       (let f ((c1 #'c1) (c2* #'(c2 ...)))
         (syntax-case c2* ()
           (()
            (syntax-case c1 (else =&gt;)
             (((else e1 e2 ...) #'(begin e1 e2 ...))
              ((e0) #'e0)
              ((e0 =&gt; e1)
               #'(let ((t e0)) (if t (e1 t))))
              ((e0 e1 e2 ...)
               #'(if e0 (begin e1 e2 ...)))))
           ((c2 c3 ...)
            (with-syntax ((rest (f #'c2 #'(c3 ...))))
              (syntax-case c1 (=&gt;)
                ((e0) #'(let ((t e0)) (if t t rest)))
                ((e0 =&gt; e1)
                 #'(let ((t e0)) (if t (e1 t) rest)))
                ((e0 e1 e2 ...)
                 #'(if e0 
                        (begin e1 e2 ...)
                        rest)))))))))))
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667878639136" class="indexterm"/> <code class="function">quasisyntax</code> <em class="replaceable"><code><em class="replaceable"><code>template</code></em></code></em></p>
        <p class="synopsis" kind="Auxiliary Syntax"><span class="kind">Auxiliary Syntax</span><span class="ignore">: </span><a id="idm139667878636176" class="indexterm"/> <code class="function">unsyntax</code></p>
        <p class="synopsis" kind="Auxiliary Syntax"><span class="kind">Auxiliary Syntax</span><span class="ignore">: </span><a id="idm139667878633760" class="indexterm"/> <code class="function">unsyntax-splicing</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The <code class="literal">quasisyntax</code> form is similar to <code class="literal">syntax</code>, but it allows
parts of the quoted text to be evaluated, in a manner similar to the
operation of <code class="literal">quasiquote</code>.
</p>
            <p>Within a <code class="literal">quasisyntax</code> <em class="replaceable"><code>template</code></em>, subforms of <code class="literal">unsyntax</code>
and <code class="literal">unsyntax-splicing</code> forms are evaluated, and everything else is
treated as ordinary template material, as with <code class="literal">syntax</code>.
</p>
            <p>The value of each <code class="literal">unsyntax</code> subform is inserted into the output in
place of the <code class="literal">unsyntax</code> form, while the value of each
<code class="literal">unsyntax-splicing</code> subform is spliced into the surrounding list or
vector structure.  Uses of <code class="literal">unsyntax</code> and <code class="literal">unsyntax-splicing</code>
are valid only within <code class="literal">quasisyntax</code> expressions.
</p>
            <p>A <code class="literal">quasisyntax</code> expression may be nested, with each
<code class="literal">quasisyntax</code> introducing a new level of syntax quotation and each
<code class="literal">unsyntax</code> or <code class="literal">unsyntax-splicing</code> taking away a level of
quotation.  An expression nested within <span class="emphasis"><em>n</em></span> <code class="literal">quasisyntax</code>
expressions must be within <span class="emphasis"><em>n</em></span> <span class="emphasis"><em>unsyntax</em></span> or
<code class="literal">unsyntax-splicing</code> expressions to be evaluated.
</p>
            <p>As noted in <a class="link" href="Datum-syntax.xhtml#meta-abbreviation"><em class="replaceable"><code>abbreviation</code></em></a>, <code class="literal">#`<em class="replaceable"><code>template</code></em></code> is equivalent to
<code class="literal">(quasisyntax <em class="replaceable"><code>template</code></em>)</code>, <code class="literal">#,<em class="replaceable"><code>template</code></em></code> is
equivalent to <code class="literal">(unsyntax <em class="replaceable"><code>template</code></em>)</code>, and
<code class="literal">#,@<em class="replaceable"><code>template</code></em></code> is equivalent to <code class="literal">(unsyntax-splicing
<em class="replaceable"><code>template</code></em>)</code>.  <span class="emphasis"><em>Note</em></span> that for backwards compatibility,
you should only use <code class="literal">#,<em class="replaceable"><code>template</code></em></code> inside a literal <code class="literal">#`<em class="replaceable"><code>template</code></em></code> form.
</p>
            <p>The <code class="literal">quasisyntax</code> keyword can be used in place of
<code class="literal">with-syntax</code> in many cases.  For example, the definition of
<code class="literal">case</code> shown under the description of <code class="literal">with-syntax</code> above can
be rewritten using <code class="literal">quasisyntax</code> as follows.
</p>
            <pre class="screen">(define-syntax case
  (lambda (x)
    (syntax-case x ()
      ((_ e c1 c2 ...)
       #`(let ((t e))
           #,(let f ((c1 #'c1) (cmore #'(c2 ...)))
               (if (null? cmore)
                   (syntax-case c1 (else)
                     ((else e1 e2 ...)
                      #'(begin e1 e2 ...))
                     (((k ...) e1 e2 ...)
                      #'(if (memv t '(k ...))
                            (begin e1 e2 ...))])
                   (syntax-case c1 ()
                     (((k ...) e1 e2 ...)
                      #`(if (memv t '(k ...))
                            (begin e1 e2 ...)
                            #,(f (car cmore)
                                  (cdr cmore))))))))))))
</pre>
          </blockquote>
        </div>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p><span class="emphasis"><em>Note:</em></span> Any <code class="literal">syntax-rules</code> form can be expressed with
<code class="literal">syntax-case</code> by making the <code class="literal">lambda</code> expression and
<code class="literal">syntax</code> expressions explicit, and <code class="literal">syntax-rules</code> may be
defined in terms of <code class="literal">syntax-case</code> as follows.
</p>
            <pre class="screen">(define-syntax syntax-rules
  (lambda (x)
    (syntax-case x ()
      ((_ (lit ...) ((k . p) t) ...)
       (for-all identifier? #'(lit ... k ...))
       #'(lambda (x)
           (syntax-case x (lit ...)
             ((_ . p) #'t) ...))))))
</pre>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Macros.xhtml#idm139667878937936">Pattern language</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Macros.xhtml#idm139667878770304">Identifier predicates</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Macros.xhtml#idm139667878720528">Syntax-object and datum conversions</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Macros.xhtml#idm139667878677280">Signaling errors in macro transformers</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Macros.xhtml#idm139667878656608">Convenience forms</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Syntax.xhtml">Syntax</a></p>
        <p>
        Previous: <a accesskey="p" href="Syntax-and-conditional-compilation.xhtml">Syntax and conditional compilation</a></p>
        <p>
        Next: <a accesskey="n" href="Named-quasi-literals.xhtml">Named quasi-literals</a></p>
      </div>
    </footer>
  </body>
</html>
